home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
IRIX Base Documentation 1998 November
/
IRIX 6.5.2 Base Documentation November 1998.img
/
usr
/
share
/
catman
/
p_man
/
cat3
/
lmsgi.z
/
lmsgi
Wrap
Text File
|
1998-10-30
|
25KB
|
925 lines
llllmmmmssssggggiiii((((3333)))) llllmmmmssssggggiiii((((3333))))
NNNNAAAAMMMMEEEE
lmsgi : license_init, license_chk_out, license_chk_in, license_timer,
license_set_attr, license_expdate, license_errstr, license_status - SGI
FFFFLLLLEEEEXXXXllllmmmm library
HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE
#include <lmsgi.h>
DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
This manual page describes the SGI interface to _l_i_b_l_m_s_g_i._a, the SGI
extension to Globetrotter Software's FLEXlm library. This library
supports the interfaces provided by FLEXlm as well as the functions
described here.
The SGI interface defines a small set of functions for licensing your
software using the FLEXlm, and consists of the following calls:
license_init
license_chk_out
license_chk_in
license_timer
license_set_attr
license_expdate
license_errstr
license_status
get_job
When using any of the liblmsgi library functions you must include the
following header and macro in your source file:
#include <lmsgi.h>
LM_CODE(code, ENCRYPTION_CODE_1, ENCRYPTION_CODE_2,
VENDOR_KEY1, VENDOR_KEY2, VENDOR_KEY3,
VENDOR_KEY4, VENDOR_KEY5);
The -_l_l_m_s_g_i flag must be given to the C compiler to link programs which
contain calls to FLEXlm functions.
cc file.o -llmsgi
EEEENNNNVVVVIIIIRRRROOOONNNNMMMMEEEENNNNTTTT
The following environment variables will modify the behavior of
applications licensed with this library.
LLLLMMMM____LLLLIIIICCCCEEEENNNNSSSSEEEE____FFFFIIIILLLLEEEE
If set, specifies the name of one or more FLEXlm license files.
Multiple files can be specified by separating them with a colon (::::).
The specified files are checked first for FLEXlm licenses.
PPPPaaaaggggeeee 1111
llllmmmmssssggggiiii((((3333)))) llllmmmmssssggggiiii((((3333))))
LLLLMMMM____LLLLIIIICCCCEEEENNNNSSSSEEEE____DDDDBBBB
If set, specifies the name of a license file database. A license
file database is a file which contains a list of one or more FLEXlm
license files and/or directories containing FLEXlm license files.
If _L_M__L_I_C_E_N_S_E__D_B is not defined the default license file database,
/_v_a_r/_f_l_e_x_l_m/_l_i_c_e_n_s_e_f_i_l_e._d_b, is used.
The format of a license file database is one file or directory per
line. Comments are indicated by a pound sign '#' in the first
column of the line. Blank lines are ignored. Trailing and/or
leading whitespace is not allowed on a line.
Any directory listed in the file is searched for filenames matching
"*._d_a_t". Any subdirectory is also searched (recursively). All file
names must also end with the "*._d_a_t" extension.
If no license files have been defined by either the _L_M__L_I_C_E_N_S_E__F_I_L_E or
_L_M__L_I_C_E_N_S_E__D_B environment variables, the default FLEXlm license file is
/_v_a_r/_f_l_e_x_l_m/_l_i_c_e_n_s_e._d_a_t.
PPPPaaaaggggeeee 2222
llllmmmmssssggggiiii((((3333)))) llllmmmmssssggggiiii((((3333))))
NNNNAAAAMMMMEEEE
license_init - Initializes the FFFFLLLLEEEEXXXXllllmmmm library.
SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
#include <lmsgi.h>
int license_init (VENDORCODE* code, char *vendorname,
boolean_t heartbeat);
DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
_l_i_c_e_n_s_e__i_n_i_t() initializes the FFFFLLLLEEEEXXXXllllmmmm library and creates a license job.
All subsequent calls to license_init() create new license jobs. Each
license is independent.
ccccooooddddeeee Use the global variable "code" which was defined by the LM_CODE
macro (see above).
vvvveeeennnnddddoooorrrrnnnnaaaammmmeeee
The name of the vendor daemon to use.
hhhheeeeaaaarrrrttttbbbbeeeeaaaatttt
This is B_FALSE or B_TRUE. If B_FALSE, then a default heartbeat
protocol is implemented. FFFFLLLLEEEEXXXXllllmmmm will generate a SIGALRM at every
LM_A_CHECK_INTERVAL. This will make a call to license_timer(). If
B_TRUE, then the SIGALRM is not generated, and it is up the
application to call license_timer() periodically.
EEEEXXXXAAAAMMMMPPPPLLLLEEEE
/*
* The following code initializes the FFFFLLLLEEEEXXXXllllmmmm library and
* uses sgifd as the vendor daemon. If any errors are detected,
* then display them.
*/
if ( license_init (&code, "sgifd", B_FALSE) < 0 ) {
printf ("Initialization error: %s\n", license_errstr());
}
DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
license_init() returns a 0 upon success or a value less than 0 if an
error is detected. The error string can viewed via license_errstr().
PPPPaaaaggggeeee 3333
llllmmmmssssggggiiii((((3333)))) llllmmmmssssggggiiii((((3333))))
NNNNAAAAMMMMEEEE
license_chk_out - Attempts to check out a license.
SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
#include <lmsgi.h>
int license_chk_out(VENDORCODE *code, char *feature, char *version);
DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
_l_i_c_e_n_s_e__c_h_k__o_u_t() checks out one (or more) license(s) for the specified
feature and, for counted licenses, keeps the daemon up to date on the
status of the process using the license(s).
ccccooooddddeeee Use the global variable "code" which was defined by the LM_CODE
macro (see above).
ffffeeeeaaaattttuuuurrrreeee
The ASCII feature name desired.
vvvveeeerrrrssssiiiioooonnnn
The version of the feature desired in floating point format, 3
decimal places max. This value must be less than or equal to the
version number in the license file for the check out to succeed.
The default behavior of this library when a license request fails is to
print the standard SGI feature not found message and exit. To override
this behavior, applications should set the attribute
_L_M_S_G_I__N_O__S_U_C_H__F_E_A_T_U_R_E using _l_i_c_e_n_s_e__s_e_t__a_t_t_r to register their own
callback before calling license_chk_out.
DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
license_chk_out() returns a 0 upon success or a value less than 0 if an
error is detected. The error string can viewed via license_errstr().
PPPPaaaaggggeeee 4444
llllmmmmssssggggiiii((((3333)))) llllmmmmssssggggiiii((((3333))))
NNNNAAAAMMMMEEEE
license_chk_in - Return a checked out license.
SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
#include <lmsgi.h>
int license_chk_in(char *feature, int keep_conn);
DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
_l_i_c_e_n_s_e__c_h_k__i_n() checks in the license of the specified feature that had
been previously checked out with license_chk_out().
ffffeeeeaaaattttuuuurrrreeee
The feature (license) name to be checked in.
kkkkeeeeeeeepppp____ccccoooonnnnnnnn
A non-zero means "_K_e_e_p _c_o_n_n_e_c_t_i_o_n _t_o _s_e_r_v_e_r"; a 0 means drop TCP
connection. A zero should always be used as the default. Unused
for UDP.
Consult the _F_L_E_X_l_m _P_r_o_g_r_a_m_m_e_r'_s _G_u_i_d_e for more details.
EEEEXXXXAAAAMMMMPPPPLLLLEEEE
/*
* The following code returns the license, _d_u_m_m_y, back to the
* server. If any errors are detected, then display them.
*/
if ( license_chk_in ("dummy", 0) ) {
printf ("Check in error: %s\n", license_errstr());
}
DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
license_chk_in() returns a 0 upon success or a value less than 0 if an
error is detected. The error string can viewed via license_errstr().
PPPPaaaaggggeeee 5555
llllmmmmssssggggiiii((((3333)))) llllmmmmssssggggiiii((((3333))))
NNNNAAAAMMMMEEEE
license_timer - Verifies the connection to the license server.
SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
#include <lmsgi.h>
void license_timer();
DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
Periodic calls to _l_i_c_e_n_s_e__t_i_m_e_r() should be throughout the user's
application. These calls are important because they verify that the
license currently checked out to your application remains valid. The
user may want to call license_timer() before important steps in the
program (for example, before writing a file to disk).
EEEEXXXXAAAAMMMMPPPPLLLLEEEE
/*
* application code
*/
license_timer();
/*
* some more application code and then
* verify connection before writing to disk
*/
license_timer();
/*
* some more application code
*/
PPPPaaaaggggeeee 6666
llllmmmmssssggggiiii((((3333)))) llllmmmmssssggggiiii((((3333))))
NNNNAAAAMMMMEEEE
license_set_attr - Used to set different FFFFLLLLEEEEXXXXllllmmmm attributes.
SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
#include <lmsgi.h>
int license_set_attr(int key, LM_A_VAL_TYPE value);
DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
_l_i_c_e_n_s_e__s_e_t__a_t_t_r() set a FFFFLLLLEEEEXXXXllllmmmm attribute. The key describes which
attribute to set and value describes the value for that attribute. A
description of the attributes can be found in the FFFFLLLLEEEEXXXXllllmmmm _P_r_o_g_r_a_m_m_e_r'_s
_G_u_i_d_e or the header file _l_m__a_t_t_r._h.
kkkkeeeeyyyy The FFFFLLLLEEEEXXXXllllmmmm attribute to set.
vvvvaaaalllluuuueeee
Value to set the key to. Values should be of the appropriate type
for the particular attribute, but should be cast to LM_A_VAL_TYPE.
NNNNOOOOTTTTEEEESSSS
Four additional attributes have been defined in lmsgi:
LLLLMMMMSSSSGGGGIIII____NNNNOOOO____SSSSUUUUCCCCHHHH____FFFFEEEEAAAATTTTUUUURRRREEEE
A pointer to a function which is called when the requested feature
cannot be checked out. This function is only called if
_l_i_c_e_n_s_e__c_h_k__o_u_t() fails with an _L_M__N_O_F_E_A_T_U_R_E error.
LLLLMMMMSSSSGGGGIIII____33330000____DDDDAAAAYYYY____WWWWAAAARRRRNNNNIIIINNNNGGGG
A pointer to a function which is called when the requested feature
will expire within 30 days.
LLLLMMMMSSSSGGGGIIII____66660000____DDDDAAAAYYYY____WWWWAAAARRRRNNNNIIIINNNNGGGG
A pointer to a function which is called when the requested feature
will expire within 60 days.
LLLLMMMMSSSSGGGGIIII____99990000____DDDDAAAAYYYY____WWWWAAAARRRRNNNNIIIINNNNGGGG
A pointer to a function which is called when the requested feature
will expire within 90 days.
The _l_m_s_g_i library sets default values for attributes in order to
provide standardized error handling and error messages for SGI
software. To disable a pre-set attribute, either use
_l_i_c_e_n_s_e__s_e_t__a_t_t_r() to register a new callback that provides your
desired behavior, or register a _N_U_L_L callback to turn off the
default behavior.
The pre-set attributes are as follows:
PPPPaaaaggggeeee 7777
llllmmmmssssggggiiii((((3333)))) llllmmmmssssggggiiii((((3333))))
LLLLMMMMSSSSGGGGIIII____NNNNOOOO____SSSSUUUUCCCCHHHH____FFFFEEEEAAAATTTTUUUURRRREEEE
This attribute is set to a function which displays information on
how to get a license for an SGI product. This function also calls
_e_x_i_t(), thus the application exits when the requested feature cannot
be checked out.
LLLLMMMMSSSSGGGGIIII____33330000____DDDDAAAAYYYY____WWWWAAAARRRRNNNNIIIINNNNGGGG
This attribute is set to do nothing if the license is about to
expire within 30 days.
LLLLMMMMSSSSGGGGIIII____66660000____DDDDAAAAYYYY____WWWWAAAARRRRNNNNIIIINNNNGGGG
This attribute is set to do nothing if the license is about to
expire within 60 days.
LLLLMMMMSSSSGGGGIIII____99990000____DDDDAAAAYYYY____WWWWAAAARRRRNNNNIIIINNNNGGGG
This attribute is set to do nothing if the license is about to
expire within 90 days.
LLLLMMMM____AAAA____UUUUSSSSEEEERRRR____RRRREEEECCCCOOOONNNNNNNNEEEECCCCTTTT
This attribute is set to a function which displays a message noting
that the connection to the license server was lost, and an attempt
is being made to reconnect to the server.
LLLLMMMM____AAAA____UUUUSSSSEEEERRRR____RRRREEEECCCCOOOONNNNNNNNEEEECCCCTTTT____DDDDOOOONNNNEEEE
This attribute is set to a function which displays a message noting
that the connection to the license server was lost, and the attempt
to reconnect to the server was successful.
LLLLMMMM____AAAA____UUUUSSSSEEEERRRR____EEEEXXXXIIIITTTTCCCCAAAALLLLLLLL
This attribute is set to a function which displays a message noting
that the connection to the license server was lost, and the attempt
to reconnect to the server has failed. This function also calls
_e_x_i_t(), thus the application exits when the reconnect fails.
EEEEXXXXAAAAMMMMPPPPLLLLEEEE
/*
* The following code sets the LM_A_RETRY_COUNT to 5.
* If any errors are detected, then display them.
*/
if ( license_set_attr(LM_A_RETRY_COUNT, (LM_A_VAL_TYPE) 5) ) {
printf("Set attribute error: %s\n", license_errstr());
}
/*
* The following code displays a message when a license will expire
* within 90 days.
*/
int expire_soon(daysLeft)
int daysLeft;
PPPPaaaaggggeeee 8888
llllmmmmssssggggiiii((((3333)))) llllmmmmssssggggiiii((((3333))))
{
(void) fprintf(stderr,
"Your software license will expire in %d days.\n",
daysLeft);
return 0;
}
/*
* The following code registers a callback for a license which
* will expire soon.
*/
if ( license_set_attr(LMSGI_30_DAY_WARNING, (LM_A_VAL_TYPE) expire_soon) ) {
printf("Set attribute error: %s\n", license_errstr());
}
DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
license_set_attr() returns a 0 upon success or a value less than 0 if an
error is detected. The error string can viewed via license_errstr().
PPPPaaaaggggeeee 9999
llllmmmmssssggggiiii((((3333)))) llllmmmmssssggggiiii((((3333))))
NNNNAAAAMMMMEEEE
license_expdate - Returns the expiration date of the feature checked out.
SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
#include <lmsgi.h>
time_t license_expdate(char *feature);
DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
_l_i_c_e_n_s_e__e_x_p_d_a_t_e() returns the expiration date of a feature (license).
ffffeeeeaaaattttuuuurrrreeee
The name of the feature (license).
EEEEXXXXAAAAMMMMPPPPLLLLEEEE
/*
* The following code returns the expiration date of the
* feature, _d_u_m_m_y.
* If any errors are detected, then display them.
*/
time_t feature_expdate;
if ( ( feature_expdate = license_expdate("dummy") ) == -1 )
printf ("Expiration date error: %s\n", license_errstr());
DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
license_expdate() returns the expiration date of the given feature in
seconds since 00:00:00 UTC, January 1, 1970. If the given feature is a
permanent feature (no expiration date) then license_expdate() returns 0.
If an error occurs, a value of (time_t)-1 is returned.
Any error string can viewed via license_errstr().
PPPPaaaaggggeeee 11110000
llllmmmmssssggggiiii((((3333)))) llllmmmmssssggggiiii((((3333))))
NNNNAAAAMMMMEEEE
license_errstr - Returns license server or system errors.
SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
#include <lmsgi.h>
char* license_errstr();
DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
_l_i_c_e_n_s_e__e_r_r_s_t_r() returns the FFFFLLLLEEEEXXXXllllmmmm error string for the most recent
FFFFLLLLEEEEXXXXllllmmmm error along with the major and minor number. If a UUUUNNNNIIIIXXXX error is
involved, the UUUUNNNNIIIIXXXX error description will also be included in the
message, along with the UUUUNNNNIIIIXXXX _e_r_r_n_o.
EEEEXXXXAAAAMMMMPPPPLLLLEEEE
/*
* The following code prints out the error
*
* Cannot find license file (-1, 73:2), No such file or directory
*
* when the license file cannot be accessed.
*
*/
printf ("%s\n", license_errstr());
PPPPaaaaggggeeee 11111111
llllmmmmssssggggiiii((((3333)))) llllmmmmssssggggiiii((((3333))))
NNNNAAAAMMMMEEEE
license_status - Returns the latest status of the checked out feature.
SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
#include <lmsgi.h>
int license_status(char *feature);
DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
_l_i_c_e_n_s_e__s_t_a_t_u_s() returns the status of the requested feature (license).
A return value of 0 indicates a successful return from the most recent
call to the FFFFLLLLEEEEXXXXllllmmmm library for that feature. A return value value less
than 0 indicates an error from most recent call to the FFFFLLLLEEEEXXXXllllmmmm library.
ffffeeeeaaaattttuuuurrrreeee
The name of the feature.
EEEEXXXXAAAAMMMMPPPPLLLLEEEE
/*
* The following code checks the status of the most recent FFFFLLLLEEEEXXXXllllmmmm
* library call. If any errors occurred, then display them.
*/
license_chk_out (&code, "dummy", "2.000");
if ( license_status ("dummy") < 0 ) {
printf ("error: %s\n", license_errstr());
}
PPPPaaaaggggeeee 11112222
llllmmmmssssggggiiii((((3333)))) llllmmmmssssggggiiii((((3333))))
NNNNAAAAMMMMEEEE
get_job - Returns the FLEXlm job ID.
SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
#include <lmsgi.h>
LM_HANDLE *get_job(void);
DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
Returns the FLEXlm job ID so that applications can use the standard
FLEXlm functions along with the SGI interface.
A return value of NULL indicates that there is currently no FLEXlm job
ID.
EEEEXXXXAAAAMMMMPPPPLLLLEEEE
LM_HANDLE *job;
job = get_job();
PPPPaaaaggggeeee 11113333
llllmmmmssssggggiiii((((3333)))) llllmmmmssssggggiiii((((3333))))
RRRREEEESSSSTTTTRRRRIIIICCCCTTTTIIIIOOOONNNNSSSS
The FlexLM licensing code uses the stdio functions (_f_o_p_e_n(), _f_g_e_t_s(),
etc). In some circumstances, a process may have more open file
descriptors than will fit in a FILE structure (field __f_i_l_e; see
/usr/include/stdio.h for details). If this happens before the licensing
calls, acquiring the license will fail with the message:
Cannot find license file (-1,212:2) No such file or directory
The only solution is to reduce the number of file descriptors in use when
licensing calls are made. In practice this is only a problem with the O32
(5.3 compatible) ABI, which uses an _u_n_s_i_g_n_e_d _c_h_a_r to hold the file
descriptor (fd<=255).
PPPPaaaaggggeeee 11114444